Skip to content

feat: pubsub#1151

Draft
nugaon wants to merge 12 commits intoethersphere:masterfrom
Apiary-Suite:master
Draft

feat: pubsub#1151
nugaon wants to merge 12 commits intoethersphere:masterfrom
Apiary-Suite:master

Conversation

@nugaon
Copy link
Copy Markdown
Member

@nugaon nugaon commented Apr 20, 2026

Add Pubsub Module

Introduces a new pubsub module that wraps Bee's (G)SOC-based PubSub WebSocket API, along with supporting types, tests and documentation.

What's added

  • pubsubConnect(mode, handler, brokerPeer, ...params) — opens a WebSocket to GET /pubsub/:topicAddress and returns a subscription with send(payload) and cancel().
  • listPubsubTopics()GET /pubsub/ returning active topics with role (broker / subscriber / publisher) and connection info.
  • GsocEphemeralMode — SOC-based pubsub mode implementing the IPubsubMode interface (topicAddress, getPublisherHeaders, encodeMessage, decodeMessage). Frame layout: [sig:65B][span:4B][payload].
  • createPubsubMode(mode, ...) — generic factory with constructor-parameter inference keyed by the PubsubMode enum.

Three signer variants (discriminated union on GsocEphemeralParams)

  • Ephemeral signer{ topic: string | Uint8Array }. A string is keccak256-hashed to derive the 32-byte private key; a Uint8Array / hex string is used as the private key directly. Can publish.
  • External signer{ address, signFn }. Can publish; signs off-chunk via user-provided signFn. Address is carried in the swarm-pubsub-gsoc-eth-address header (hex, no 0x prefix).
  • Subscriber-only{ topicAddress }. Read-only, no signer; getPublisherHeaders() returns null and encodeMessage() throws.

All variants support an optional socId (string → keccak256, or 32-byte Uint8Array; defaults to NULL_IDENTIFIER). For publisher variants, topicAddress is computed internally as makeSOCAddress(socIdentifier, signerAddress).

Other changes

  • prepareWebsocketData made synchronous for consistency with websocket data types.
  • Unit tests added for encode/decode round-trips, frame structure, deterministic headers, custom socId, external signer, subscriber-only mode, Uint8Array topic, and the mode factory.
  • README Bee API table updated with pubsubConnect, listPubsubTopics, and gsocSubscribe.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants